Introduction

JAI is a advanced image manipulation library built by Sun and distributed with an open source license.
JAI Image I/O is a set of image reader/writers that add extra formats or extra capabilities to the ImageIO that ships with the standard JDK.

These libraries comprise of a pure java part, which sports full functinality by itself, and a set of native libraries for selected operating system that boost its performance.

Geoserver and JAI

Geoserver 1.5.0 uses both of them in its WCS and WMS modules.
Unfortunately, installing JAI has proven to be a troblesome process, so we decided to ship the pure java versions of JAI and JAI Image I/O in Geoserver itself, instead of asking people to install them in the JDK.
This allows Geoserver to run out of the box on a vanilla JDK, but has a couple of drawbacks:

• performance is inferior to the one delivered by native extensions;
• if native extensions are installed, some container (Jetty) classloaders cause problems and prevent Geoserver from working at all.

The following guide tries to walk you thru the issues you may encounter playing with native JAI.

Installing native JAI

Geotools has a quite detailed guide on how to install JAI and JAI Image I/O, please refer to it for details on installation.

Once you have installed JAI, if you want, you may unpack the Geosever WAR file and remove the jai related files (this is the best cure for all classloading issues): jai_core-x.y.z.jar, jai_imageio-x.y.jar and jai_codec-x.y.z.jar.

Running on JDK 1.4

If you're running on JDK 1.4 (and cannot upgrade to a newer JDK), you should see a message on the Geoserver startup logs stating:

WARNING: Disabling mediaLib acceleration since this is a java 1.4 VM.
If you want to force its enabling, set -Dcom.sun.media.imageio.disableCodecLib=false in your virtual machine

If you see it, and have native JAI installed, in order to make native JAI be eneabled and working you have to:

• remove the jai_core-x.y.z.jar,jai_imageio-x.y.jar and jai_codec-x.y.z.jar jar files from your Geoserver install
• start Geoserver with the -Dcom.sun.media.imageio.disableCodecLib=false JVM parameter, in addition to whatever parameter you may have set already.

Dealing with Jetty's classloader

Jetty by default ships with a classloader that does not conform to the Java classloading model: you'll notice because Geoserver will fail all JAI usage attempt with a "sealing violation" exception. Happily, it can be restored to standard behaviour locating the etc/jetty.xml configuration file and changing the web app context configuration to look like the following:

<Call class="org.mortbay.jetty.webapp.WebAppContext" name="addWebApplications">
  <Arg><Ref id="contexts"/></Arg>
  <Arg><SystemProperty name="jetty.home" default="."/>/webapps</Arg>
  <Arg><SystemProperty name="jetty.home" default="."/>/etc/webdefault.xml</Arg>
  <Arg type="boolean">True</Arg>  <!-- extract -->
  <Arg type="boolean">True</Arg> <!-- parent priority class loading -->
</Call>